/*
Copyright 2009 Swivel4J

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package org.swivel4j.chart;

/**
 * Basic CRUD opertions for Swivel charts.
 * @author Ken Weiner
 * @version $Id: ChartClient.java 14 2009-11-30 23:04:14Z kweiner $
 */
public interface ChartClient {
	/**
	 * Creates a new chart with the given name and data.
	 * Keep track of the chart ID as given by {@link Chart#getId()}
	 * It will be used for reading, updating, and deleting the chart.
	 * @param name the chart name
	 * @param description the chart description (can be null)
	 * @param data the initial chart data in CSV format
     * @param groupId the ID of the group that you want to publish the chart to (can be null).
     *     If this parameter is not passed, it will default to your drafts group.
     *     Pass an empty groupId to publish the chart publicly.
     * @param options a set of options, as a JSON string, that describe the look and feel of the chart
     *     (can be null).
	 * @return the chart metadata
	 */
    Chart createChart(String name, String description, String data, Integer groupId, String options);

    /**
     * Gets the chart metadata given a chart ID.
     * @param chartId the chart ID
     * @return the chart metadata
     */
    Chart getChartMetadata(Integer chartId);

    /**
     * Gets the chart data given a chart ID.
     * @param chartId the chart ID
     * @return the chart data in CSV format
     */
    String getChartData(Integer chartId);

    /**
     * Replaces a chart's data with a new set of data.
     * @param chartId the chart ID
     * @param data the chart data in CSV format
     */
    void replaceChartData(Integer chartId, String data);

    /**
     * Appends data to an existing chart.
     * @param chartId the chart ID
     * @param data the chart data to append in CSV format
     */
    void appendDataToChart(Integer chartId, String data);

    /**
     * Deletes a chart with the given chart ID.
     * @param chartId the chart ID
     */
    void deleteChart(Integer chartId);
}
